<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><meta name="generator" content="MATLAB R2018a"><meta http-equiv="X-UA-Compatible" content="IE=edge,IE=9,chrome=1"><title>Getting Started with MATLAB-NS3 Cosimulation</title><style type="text/css">
* {margin: 0; padding: 0;}
body {text-align: start; line-height: 17.234001159668px; min-height: 0px; white-space: normal; color: rgb(0, 0, 0); font-family: Menlo, Monaco, Consolas, 'Courier New', monospace; font-style: normal; font-size: 13.9999990463257px; font-weight: normal; text-decoration: none; white-space: normal; }
h1, h2 {font-weight: normal;}
.content { padding: 30px; }

.S0 { margin-left: 0px; margin-top: 0px; margin-bottom: 0px; margin-right: 0px;  }
.S1 { text-align: left; line-height: 26.3999977111816px; min-height: 24px; white-space: pre-wrap; color: rgb(213, 80, 0); font-family: Helvetica, Arial, sans-serif; font-size: 22px; white-space: pre-wrap; margin-left: 4px; margin-top: 3px; margin-bottom: 15px; margin-right: 10px;  }
.S2 { min-height: 0px; margin-left: 0px; margin-top: 0px; margin-bottom: 0px; margin-right: 0px;  }
.S3 { text-align: left; line-height: 20.576000213623px; min-height: 20px; white-space: pre-wrap; color: rgb(60, 60, 60); font-family: Helvetica, Arial, sans-serif; font-size: 16px; font-weight: bold; white-space: pre-wrap; margin-left: 4px; margin-top: 15px; margin-bottom: 9px; margin-right: 10px;  }
.S4 { text-align: left; line-height: 21px; min-height: 17px; white-space: pre-wrap; font-family: Helvetica, Arial, sans-serif; white-space: pre-wrap; margin-left: 4px; margin-top: 2px; margin-bottom: 9px; margin-right: 10px;  }
.S5 { font-family: Helvetica, Arial, sans-serif; margin-left: 0px; margin-top: 10px; margin-bottom: 20px; margin-right: 0px;  }
.S6 { text-align: left; line-height: 20.9999980926514px; white-space: pre-wrap; white-space: pre-wrap; margin-left: 55.9999961853027px; margin-top: 0px; margin-bottom: 0px; margin-right: 0px;  }
.S7 { text-decoration: underline; margin-left: 0px; margin-top: 0px; margin-bottom: 0px; margin-right: 0px;  }
.S8 { font-style: italic; margin-left: 0px; margin-top: 0px; margin-bottom: 0px; margin-right: 0px;  }

.CodeBlock {margin: 10px 0 10px 0; background-color: #F7F7F7;}
.CodeBlock+.paragraphNode {margin-top: 10px;}
.lineNode {padding-left: 10px; border-left: 1px solid #E9E9E9; border-right: 1px solid #E9E9E9;}
.inlineWrapper:first-child .lineNode,.inlineWrapper.outputs+.inlineWrapper .lineNode {padding-top: 5px; border-top: 1px solid #E9E9E9;}
.inlineWrapper:last-child .lineNode,.inlineWrapper.outputs .lineNode {padding-bottom: 5px; border-bottom: 1px solid #E9E9E9;}
.lineNode .textBox {white-space: pre;}
</style></head><body><div class = "content"><div class = 'SectionBlock containment active'><h1 class = "S1"><span class = "S2"><span class="S0">Getting Started with MATLAB-NS3 Cosimulation</span></span></h1><h2 class = "S3"><span class = "S2"><span class="S0">I</span></span><span class = "S2"><span class="S0">ntroduction</span></span></h2><div class = "S4"><span class = "S2"><span class="S0">This document describes the underlying architecture used for realizing co-simulation, combining the powers of MATLAB and NS-3.</span></span></div><div class = "S4"><span class = "S2"><span class="S0"></span></span></div><h2 class = "S3"><span class = "S2"><span class="S0">Why co-simulate with NS3</span></span></h2><div class = "S4"><span class = "S2"><span class="S0">NS-3 is a discrete event network simulator and enjoys huge user base in research community. It has well defined implementation of major network protocol stacks for system-level simulation. The aim of this co-simulation is to leverage the protocol stacks of NS-3 from MATLAB and make it easy for users to simulate complex network scenarios.</span></span></div><div class = "S4"><span class = "S2"><span class="S0"></span></span></div><h2 class = "S3"><span class = "S2"><span class="S0">Benefits for the MATLAB user:</span></span></h2><ol class = "S5"><li class = "S6"><span class = "S0"><span class="S0">Do system level modeling of communication system with multiple nodes, without leaving MATLAB.</span></span></li><li class = "S6"><span class = "S0"><span class="S0">Create simulation scenarios and visualize results in MATLAB.</span></span></li><li class = "S6"><span class = "S0"><span class="S0">Allows MATLAB user not accustomed to C++, to utilize the power of NS-3.</span></span></li><li class = "S6"><span class = "S0"><span class="S0">Use MATLAB PHY &amp; Channel models, where high-fidelity results are desired.</span></span></li><li class = "S6"><span class = "S0"><span class="S0">Integrate with MATLAB components that users have already developed.</span></span></li><li class = "S6"><span class = "S0"><span class="S0">Co-simulate with other MATLAB toolboxes.</span></span></li></ol><div class = "S4"><span class = "S2"><span class="S0"></span></span></div><h2 class = "S3"><span class = "S2"><span class="S0">High-level architecture</span></span></h2><div class = "S4"><span class = "S2"><span class="S0">The following figure depicts the architecture of MATLAB and NS-3 Co-Simulation. The simulation scenario is written in MATLAB while the simulation primarily runs in NS-3. Mex-bindings act as the interface between MATLAB and NS-3. The MATLAB wrapper classes provide an abstraction layer over these Mex bindings.</span></span></div><div class = "S4"><img class="imageNode" width="775" height="353" style="vertical-align: baseline" src="" alt="image1.png"></div><div class = "S4"><span class = "S2"><span class="S0"></span></span></div><div class = "S4"><span class = "S2"><span class="S0">The simulation scenario in MATLAB consists of scenario configuration and a sequence of function calls. A function call could be internal to MATLAB, or a call into the NS-3 library via MATLAB wrappers and Mex-bindings. Each pair of Mex-binding file and MATLAB wrapper class correspond to an NS-3 C++ class.</span></span></div><div class = "S4"><span class = "S2"><span class="S0">Below diagram shows the way a sample function residing in the NS-3 library is invoked from MATLAB. The required type conversions are managed in Mex bindings.</span></span></div><div class = "S4"><img class="imageNode" style="vertical-align: baseline" src=""></div><div class = "S4"><span class = "S2"><span class="S0"></span></span></div><div class = "S4"><span class = "S2"><span class="S0">A MATLAB script calls into the NS-3 library by calling corresponding method in the MATLAB wrapper class, which in turns calls the corresponding Mex function. Finally, Mex function calls into the NS-3 library.</span></span></div><div class = "S4"><span class = "S2"><span class="S0"></span></span></div><h2 class = "S3"><span class = "S2"><span class="S0">MATLAB PHY and Channel model invocation from NS-3</span></span></h2><div class = "S4"><span class = "S2"><span class="S0">The Co-Simulation can optionally use MATLAB's Phy and Channel models, instead of NS-3's statistical models, for higher fidelity. To use MATLAB's models, a callback mechanism is used through which NS-3 protocol stack calls into MATLAB PHY implementation via Mex Interface. </span></span></div><div class = "S4"><img class="imageNode" style="vertical-align: baseline" src=""></div><div class = "S4"><span class = "S2"><span class="S0">The following files (along with corresponding header files) are added to the NS3 library, to invoke MATLAB PHY and Channel models for modeling PHY and Channel:</span></span></div><ol class = "S5"><li class = "S6"><span class = "S0"><span class="S0">matlab-wifi-helper.cc (class MatlabWifiPhyHelper, class MatlabWifiChannelHelper)</span></span></li><li class = "S6"><span class = "S0"><span class="S0">matlab-wifi-phy.cc (class MatlabWifiPhy)</span></span></li><li class = "S6"><span class = "S0"><span class="S0">matlab-wifi-channel.cc (class MatlabWifiChannel)</span></span></li></ol><div class = "S4"><span class = "S2"><span class="S0">User shall register a custom MATLAB callback function through the MatlabWifiChannelHelper, a MATLAB wrapper class. In the callback function, user typically defines the PHY tx-rx chain (containing modeling of PHY Tx, Channel and PHY Rx for the packet). </span></span></div><div class = "S4"><span class = "S2"><span class="S0">Whenever a packet from higher layers reaches the PHY &amp; Channel models in NS3, the custom model added to NS3 will pass the packet to the callback in Mex. The Mex layer passes the packet to the registered MATLAB callback of user, through 'mexCallMATLAB'. The callback is passed the required parameters along with the packet, to model the PHY and Channel in MATLAB.</span></span></div><div class = "S4"><img class="imageNode" style="vertical-align: baseline" src=""></div><div class = "S4"><span class = "S2"><span class="S0"></span></span></div><div class = "S4"><span class = "S2"><span class="S0">Currently the co-simulation with NS-3 is </span></span><span class = "S2"><span class="S7">limited to Linux platform</span></span><span class = "S2"><span class="S0">. </span></span></div><div class = "S4"><span class = "S2"><span class="S0"></span></span></div><h2 class = "S3"><span class = "S2"><span class="S0">Typical steps in creating a simulation scenario in MATLAB</span></span></h2><div class = "S4"><span class = "S2"><span class="S0">Here are the steps typically performed in creating and running a simulation scenario.</span></span></div><div class = "S4"><span class = "S2"><span class="S0">  </span></span><img class="imageNode" style="vertical-align: baseline" src=""></div><div class = "S4"><span class = "S2"><span class="S0">The scenario description starts by defining the configurable parameters, Number of nodes, network stack layers (including PHY &amp; Channel), application data traffic properties, mobility parameters, etc.</span></span></div><div class = "S4"><span class = "S2"><span class="S0">Setting up the simulation scenario involves: creating the nodes, binding the channel/phy/protocol stack on the nodes, configuring the position &amp; mobility models for nodes, and installing applications on the nodes. For visualization, logging and tracing are enabled on desirable events. The traces (generated during the runtime) are visualized in MATLAB, offline.</span></span></div><div class = "S4"><span class = "S2"><span class="S0">Once simulation set-up is complete, simulation starts. The simulation runs in MATLAB process context, through Mex call. The simulation primarily runs in NS-3. During simulation, MATLAB can get triggers through callbacks registered with NS-3 (timers, application data reception, trace notifications, and node mobility triggers). When the MATLAB gets trigger from NS-3, it can perform run-time actions such as: creating application data packet, parsing received application data and acting on it, changing the nodes mobility, etc. This run-time interaction between MATLAB and NS-3 happens through Mex interface.</span></span></div><div class = "S4"><span class = "S2"><span class="S0">MATLAB can collect the statistics while the simulation is running. The statistics can be analyzed and visualized in MATLAB.</span></span></div><div class = "S4"><span class = "S2"><span class="S0"></span></span></div></div></div><br><!-- <br>##### SOURCE BEGIN #####<br>%% Getting Started with MATLAB-NS3 Cosimulation<br>%% I*ntroduction*<br>% This document describes the underlying architecture used for realizing co-simulation, <br>% combining the powers of MATLAB and NS-3.<br>% <br>% <br>%% *Why co-simulate with NS3*<br>% NS-3 is a discrete event network simulator and enjoys huge user base in research <br>% community. It has well defined implementation of major network protocol stacks <br>% for system-level simulation. The aim of this co-simulation is to leverage the <br>% protocol stacks of NS-3 from MATLAB and make it easy for users to simulate complex <br>% network scenarios.<br>% <br>% <br>%% *Benefits for the MATLAB user:*<br>% # Do system level modeling of communication system with multiple nodes, without <br>% leaving MATLAB.<br>% # Create simulation scenarios and visualize results in MATLAB.<br>% # Allows MATLAB user not accustomed to C++, to utilize the power of NS-3.<br>% # Use MATLAB PHY & Channel models, where high-fidelity results are desired.<br>% # Integrate with MATLAB components that users have already developed.<br>% # Co-simulate with other MATLAB toolboxes.<br>% <br>% <br>%% *High-level architecture*<br>% The following figure depicts the architecture of MATLAB and NS-3 Co-Simulation. <br>% The simulation scenario is written in MATLAB while the simulation primarily <br>% runs in NS-3. Mex-bindings act as the interface between MATLAB and NS-3. The <br>% MATLAB wrapper classes provide an abstraction layer over these Mex bindings.<br>% <br>% <br>% <br>% <br>% <br>% The simulation scenario in MATLAB consists of scenario configuration and <br>% a sequence of function calls. A function call could be internal to MATLAB, or <br>% a call into the NS-3 library via MATLAB wrappers and Mex-bindings. Each pair <br>% of Mex-binding file and MATLAB wrapper class correspond to an NS-3 C++ class.<br>% <br>% Below diagram shows the way a sample function residing in the NS-3 library <br>% is invoked from MATLAB. The required type conversions are managed in Mex bindings.<br>% <br>% <br>% <br>% <br>% <br>% A MATLAB script calls into the NS-3 library by calling corresponding method <br>% in the MATLAB wrapper class, which in turns calls the corresponding Mex function. <br>% Finally, Mex function calls into the NS-3 library.<br>% <br>% <br>%% *MATLAB PHY and Channel model invocation from NS-3*<br>% The Co-Simulation can optionally use MATLAB's Phy and Channel models, instead <br>% of NS-3's statistical models, for higher fidelity. To use MATLAB's models, a <br>% callback mechanism is used through which NS-3 protocol stack calls into MATLAB <br>% PHY implementation via Mex Interface. <br>% <br>% <br>% <br>% The following files (along with corresponding header files) are added to <br>% the NS3 library, to invoke MATLAB PHY and Channel models for modeling PHY and <br>% Channel:<br>% <br>% # matlab-wifi-helper.cc (class MatlabWifiPhyHelper, class MatlabWifiChannelHelper)<br>% # matlab-wifi-phy.cc (class MatlabWifiPhy)<br>% # matlab-wifi-channel.cc (class MatlabWifiChannel)<br>% <br>% User shall register a custom MATLAB callback function through the MatlabWifiChannelHelper, <br>% a MATLAB wrapper class. In the callback function, user typically defines the <br>% PHY tx-rx chain (containing modeling of PHY Tx, Channel and PHY Rx for the packet). <br>% <br>% Whenever a packet from higher layers reaches the PHY & Channel models in <br>% NS3, the custom model added to NS3 will pass the packet to the callback in Mex. <br>% The Mex layer passes the packet to the registered MATLAB callback of user, through <br>% 'mexCallMATLAB'. The callback is passed the required parameters along with the <br>% packet, to model the PHY and Channel in MATLAB.<br>% <br>% <br>% <br>% <br>% <br>% Currently the co-simulation with NS-3 is limited to Linux platform. <br>% <br>% <br>%% *Typical steps in creating a simulation scenario in MATLAB*<br>% Here are the steps typically performed in creating and running a simulation <br>% scenario.<br>% <br>%   <br>% <br>% The scenario description starts by defining the configurable parameters, <br>% Number of nodes, network stack layers (including PHY & Channel), application <br>% data traffic properties, mobility parameters, etc.<br>% <br>% Setting up the simulation scenario involves: creating the nodes, binding <br>% the channel/phy/protocol stack on the nodes, configuring the position & mobility <br>% models for nodes, and installing applications on the nodes. For visualization, <br>% logging and tracing are enabled on desirable events. The traces (generated during <br>% the runtime) are visualized in MATLAB, offline.<br>% <br>% Once simulation set-up is complete, simulation starts. The simulation runs <br>% in MATLAB process context, through Mex call. The simulation primarily runs in <br>% NS-3. During simulation, MATLAB can get triggers through callbacks registered <br>% with NS-3 (timers, application data reception, trace notifications, and node <br>% mobility triggers). When the MATLAB gets trigger from NS-3, it can perform run-time <br>% actions such as: creating application data packet, parsing received application <br>% data and acting on it, changing the nodes mobility, etc. This run-time interaction <br>% between MATLAB and NS-3 happens through Mex interface.<br>% <br>% MATLAB can collect the statistics while the simulation is running. The <br>% statistics can be analyzed and visualized in MATLAB.<br>##### SOURCE END #####<br>--></body></html>
